<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.linalg.matrix_rank &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Linear algebra (numpy.linalg)" href="../routines.linalg.html" >
    <link rel="next" title="numpy.linalg.slogdet" href="numpy.linalg.slogdet.html" >
    <link rel="prev" title="numpy.linalg.det" href="numpy.linalg.det.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../routines.html" >Routines</a></li>
          <li class="active"><a href="../routines.linalg.html" accesskey="U">Linear algebra (<code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.linalg</span></code>)</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.linalg.slogdet.html" title="numpy.linalg.slogdet"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.linalg.det.html" title="numpy.linalg.det"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.linalg.det.html"
                        title="previous chapter">numpy.linalg.det</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.linalg.slogdet.html"
                        title="next chapter">numpy.linalg.slogdet</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-linalg-matrix-rank">
<h1>numpy.linalg.matrix_rank<a class="headerlink" href="#numpy-linalg-matrix-rank" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="numpy.linalg.matrix_rank">
<code class="sig-prename descclassname">numpy.linalg.</code><code class="sig-name descname">matrix_rank</code><span class="sig-paren">(</span><em class="sig-param">M</em>, <em class="sig-param">tol=None</em>, <em class="sig-param">hermitian=False</em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/numpy/numpy/blob/v1.18.1/numpy/linalg/linalg.py#L1770-L1872"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#numpy.linalg.matrix_rank" title="Permalink to this definition">¶</a></dt>
<dd><p>Return matrix rank of array using SVD method</p>
<p>Rank of the array is the number of singular values of the array that are
greater than <em class="xref py py-obj">tol</em>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.14: </span>Can now operate on stacks of matrices</p>
</div>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl>
<dt><strong>M</strong><span class="classifier">{(M,), (…, M, N)} array_like</span></dt><dd><p>Input vector or stack of matrices.</p>
</dd>
<dt><strong>tol</strong><span class="classifier">(…) array_like, float, optional</span></dt><dd><p>Threshold below which SVD values are considered zero. If <em class="xref py py-obj">tol</em> is
None, and <code class="docutils literal notranslate"><span class="pre">S</span></code> is an array with singular values for <em class="xref py py-obj">M</em>, and
<code class="docutils literal notranslate"><span class="pre">eps</span></code> is the epsilon value for datatype of <code class="docutils literal notranslate"><span class="pre">S</span></code>, then <em class="xref py py-obj">tol</em> is
set to <code class="docutils literal notranslate"><span class="pre">S.max()</span> <span class="pre">*</span> <span class="pre">max(M.shape)</span> <span class="pre">*</span> <span class="pre">eps</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.14: </span>Broadcasted against the stack of matrices</p>
</div>
</dd>
<dt><strong>hermitian</strong><span class="classifier">bool, optional</span></dt><dd><p>If True, <em class="xref py py-obj">M</em> is assumed to be Hermitian (symmetric if real-valued),
enabling a more efficient method for finding singular values.
Defaults to False.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.14.</span></p>
</div>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>rank</strong><span class="classifier">(…) array_like</span></dt><dd><p>Rank of M.</p>
</dd>
</dl>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>The default threshold to detect rank deficiency is a test on the magnitude
of the singular values of <em class="xref py py-obj">M</em>.  By default, we identify singular values less
than <code class="docutils literal notranslate"><span class="pre">S.max()</span> <span class="pre">*</span> <span class="pre">max(M.shape)</span> <span class="pre">*</span> <span class="pre">eps</span></code> as indicating rank deficiency (with
the symbols defined above). This is the algorithm MATLAB uses [1].  It also
appears in <em>Numerical recipes</em> in the discussion of SVD solutions for linear
least squares [2].</p>
<p>This default threshold is designed to detect rank deficiency accounting for
the numerical errors of the SVD computation.  Imagine that there is a column
in <em class="xref py py-obj">M</em> that is an exact (in floating point) linear combination of other
columns in <em class="xref py py-obj">M</em>. Computing the SVD on <em class="xref py py-obj">M</em> will not produce a singular value
exactly equal to 0 in general: any difference of the smallest SVD value from
0 will be caused by numerical imprecision in the calculation of the SVD.
Our threshold for small SVD values takes this numerical imprecision into
account, and the default threshold will detect such numerical rank
deficiency.  The threshold may declare a matrix <em class="xref py py-obj">M</em> rank deficient even if
the linear combination of some columns of <em class="xref py py-obj">M</em> is not exactly equal to
another column of <em class="xref py py-obj">M</em> but only numerically very close to another column of
<em class="xref py py-obj">M</em>.</p>
<p>We chose our default threshold because it is in wide use.  Other thresholds
are possible.  For example, elsewhere in the 2007 edition of <em>Numerical
recipes</em> there is an alternative threshold of <code class="docutils literal notranslate"><span class="pre">S.max()</span> <span class="pre">*</span>
<span class="pre">np.finfo(M.dtype).eps</span> <span class="pre">/</span> <span class="pre">2.</span> <span class="pre">*</span> <span class="pre">np.sqrt(m</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">+</span> <span class="pre">1.)</span></code>. The authors describe
this threshold as being based on “expected roundoff error” (p 71).</p>
<p>The thresholds above deal with floating point roundoff error in the
calculation of the SVD.  However, you may have more information about the
sources of error in <em class="xref py py-obj">M</em> that would make you consider other tolerance values
to detect <em>effective</em> rank deficiency.  The most useful measure of the
tolerance depends on the operations you intend to use on your matrix.  For
example, if your data come from uncertain measurements with uncertainties
greater than floating point epsilon, choosing a tolerance near that
uncertainty may be preferable.  The tolerance may be absolute if the
uncertainties are absolute rather than relative.</p>
<p class="rubric">References</p>
<dl class="citation">
<dt class="label" id="ra43e662d710b-1"><span class="brackets">1</span></dt>
<dd><p>MATLAB reference documention, “Rank”
<a class="reference external" href="https://www.mathworks.com/help/techdoc/ref/rank.html">https://www.mathworks.com/help/techdoc/ref/rank.html</a></p>
</dd>
<dt class="label" id="ra43e662d710b-2"><span class="brackets">2</span></dt>
<dd><p>W. H. Press, S. A. Teukolsky, W. T. Vetterling and B. P. Flannery,
“Numerical Recipes (3rd edition)”, Cambridge University Press, 2007,
page 795.</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">numpy.linalg</span> <span class="kn">import</span> <span class="n">matrix_rank</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">matrix_rank</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">eye</span><span class="p">(</span><span class="mi">4</span><span class="p">))</span> <span class="c1"># Full rank matrix</span>
<span class="go">4</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">I</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">eye</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span> <span class="n">I</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.</span> <span class="c1"># rank deficient matrix</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">matrix_rank</span><span class="p">(</span><span class="n">I</span><span class="p">)</span>
<span class="go">3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">matrix_rank</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">ones</span><span class="p">((</span><span class="mi">4</span><span class="p">,)))</span> <span class="c1"># 1 dimension - rank 1 unless all 0</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">matrix_rank</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">((</span><span class="mi">4</span><span class="p">,)))</span>
<span class="go">0</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>